'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH USBPRN 4D "May 17, 2020"
.SH NAME
usbprn \- USB printer class driver
.SH SYNOPSIS
.nf
#include <sys/usb/clients/printer/usb_printer.h>
.fi

.LP
.nf
#include <sys/ecppio.h>
.fi

.LP
.nf
usbprn@unit-address
.fi

.SH DESCRIPTION
The \fBusbprn\fR driver is a USBA (Solaris USB Architecture) compliant client
driver that supports the \fIUSB Printer Class 1.0\fR specification. The
\fBusbprn\fR driver supports a subset of the \fBecpp\fR(4D) parallel port
driver functionality. However, unlike the STREAMS-based \fBecpp\fR driver,
\fBusbprn\fR is a character driver.
.sp
.LP
The \fBusbprn\fR driver supports all USB printer-class compliant printers.
.sp
.LP
The \fBusbrpn\fR driver includes support for communicating with many different
printers. To use these printers, it may be necessary to install and configure
additional format conversion packages available in the Solaris distribution.
Configuration of these conversion packages under the Solaris printing system
can be simplified through the use of the \fBprintmgr\fR(8). This tool allows
selection of printer manufacturer/model information while creating a print
queue. For USB connected printers, it attempts to pre-select the
manufacturer and model information based on the 1284 device id supplied by the
printer.
.SS "UGEN (Generic USB)"
The \fBusbprn\fR driver also supports a \fBugen\fR(4D) interface allowing raw
access to the device, for example by libusb applications, by
passing the drivers bound to each interface. Because a libusb application might
change the state of the device, you should not access the device through the
child interface drivers.
.SH DEFAULT OPERATION
With certain minor exceptions (outlined in the Notes sections below), the
\fBusbprn\fR driver supports a subset of the \fBecpp\fR(4D) ioctl interfaces:
.sp
.LP
Configuration variables are set to their default values each time the USB
printer device is attached. The \fBwrite_timeout\fR period (defined in the
ECPPIOC_SETPARMS ioctl description below) is set to 90 seconds. The mode is set
to centronics mode (ECPP_CENTRONICS). Parameters can be changed through the
ECPPIOC_SETPARMS ioctl and read through the ECPPIOC_GETPARMS ioctl. Each time
the USB printer device is opened, the device is marked as busy and all further
opens will return EBUSY. Once the device is open, applications can write to the
device and the driver can send data and obtain device id and status.
.LP
Note -
.sp
.RS 2
Unlike the \fBecpp\fR(4D) driver, \fBusbprn\fR resets configuration variables
to their default values with each \fBattach\fR(9E). (The \fBecpp\fR(4D) driver
resets configuration variables with each \fBopen\fR(2).)
.RE
.SH WRITE OPERATION
A \fBwrite\fR(2) operation returns the number of bytes successfully written to
the device. If a failure occurs while a driver is transferring data to printer,
the contents of the status bits are captured at the time of the error and can
be retrieved by the application program using the ECPPIOC_GETERR \fBioctl\fR(2)
call. The captured status information is overwritten each time an
ECPPIOC_TESTIO \fBioctl\fR(2) occurs.
.SH IOCTLS
The \fBusbprn\fR driver supports \fBprnio\fR(4I) interfaces. Note that the
\fBPRNIOC_RESET\fR command has no effect on USB printers.
.sp
.LP
The following \fBioctl\fR(2) calls are supported for backward compatibility and
are not recommended for new applications.
.sp
.ne 2
.na
\fB\fBECPPIOC_GETPARMS\fR\fR
.ad
.RS 20n
Gets current transfer parameters. The argument is a pointer to \fBstruct
ecpp_transfer_parms\fR. If parameters are not configured after the device is
opened, the structure will be set to its default configuration.
.LP
Note -
.sp
.RS 2
Unlike the \fBecpp\fR(4D) driver, only the ECPP_CENTRONICS mode is currently
supported in \fBusbprn\fR.
.RE
.RE

.sp
.ne 2
.na
\fB\fBECPPIOC_SETPARMS\fR\fR
.ad
.RS 20n
Sets transfer parameters. The argument is a pointer to a \fBstruct
ecpp_transfer_parms\fR. If a parameter is out of range, \fBEINVAL\fR is
returned. If the peripheral or host device cannot support the requested mode,
\fBEPROTONOSUPPORT\fR is returned.
.sp
The transfer parameters structure is defined in <\fBsys/ecppio.h\fR>:
.sp
.in +2
.nf
struct ecpp_transfer_parms {
    int  write_timeout;
    int  mode;
};
.fi
.in -2

The \fBwrite_timeout\fR field, which specifies how long the driver will take to
transfer 8192 bytes of data to the device, is set to a default value of 90
seconds. The \fBwrite_timeout\fR field must be greater than one second and less
than 300 seconds (five minutes.)
.LP
Note -
.sp
.RS 2
Unlike the \fBecpp\fR(4D) driver, only the ECPP_CENTRONICS mode is currently
supported in \fBusbprn\fR. Also, the semantics of \fBwrite_timeout\fR in
\fBusbprn\fR differ from \fBecpp\fR(4D). Refer to \fBecpp\fR(4D) for
information.
.RE
.RE

.sp
.ne 2
.na
\fB\fBBPPIOC_TESTIO\fR\fR
.ad
.RS 20n
Tests the transfer readiness of a print device and checks status bits to
determine if a \fBwrite\fR(2) will succeed. If status bits are set, a transfer
will fail. If a transfer will succeed, zero is returned. If a transfer fails,
the driver returns \fBEIO\fR and the state of the status bits are captured. The
captured status can be retrieved using the BPPIOC_GETERR \fBioctl\fR(2) call.
.LP
Note -
.sp
.RS 2
Unlike the \fBecpp\fR(4D) driver, only the ECPP_CENTRONICS mode is currently
supported in \fBusbprn\fR. Additionally, \fBbus_error\fR and
\fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In
\fBecpp\fR(4D), \fBtimeout_occurred\fR is used.)
.RE
.RE

.sp
.ne 2
.na
\fB\fBBPPIOC_GETERR\fR\fR
.ad
.RS 20n
Get last error status. The argument is a pointer to a \fBstruct
bpp_error_status\fR. This structure indicates the status of all the appropriate
status bits at the time of the most recent error condition during a
\fBwrite\fR(2) call, or the status of the bits at the most recent BPPIOC_TESTIO
\fBioctl\fR(2) call.
.sp
.in +2
.nf
struct bpp_error_status {
   char    timeout_occurred; /* not used */
   char    bus_error;        /* not used */
   uchar_t pin_status;       /* status of pins which
                             /* could cause error */
};
.fi
.in -2

The pin_status field indicates possible error conditions. The error status
structure \fBbpp_error_status\fR is defined in the include file
\fB<sys/bpp_io.h>\fR\&. The valid bits for \fBpin_status\fR can be
\fBBPP_ERR_ERR\fR, \fBBPP_SLCT_ERR\fR, and \fBBPP_PE_ERR\fR. A set bit
indicates that the associated pin is asserted.
.LP
Note -
.sp
.RS 2
Unlike the \fBecpp\fR(4D) driver, only the ECPP_CENTRONICS mode is currently
supported in \fBusbprn\fR. Additionally, the \fBbus_error\fR and
\fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In
\fBecpp\fR(4D), \fBtimeout_occurred\fR is used.) Unlike \fBecpp\fR(4D), the
BPP_BUSY_ERR status bit is not supported by USB printers.
.RE
.RE

.sp
.ne 2
.na
\fB\fBECPPIOC_GETDEVID\fR\fR
.ad
.RS 20n
Gets the IEEE 1284 device ID from the peripheral. The argument is a pointer to
a \fBstruct ecpp_device_id\fR. Applications should set mode to ECPP_CENTRONICS.
If another mode is used, the driver will return \fBEPROTONOSUPPORT\fR.
\fBlen\fR is the length of the buffer pointed to by \fBaddr\fR. \fBrlen\fR is
the actual length of the device ID string returned from the peripheral. If the
returned \fBrlen\fR is greater than \fBlen\fR, the application should call
ECPPIOC_GETDEVID a second time with a buffer length equal to \fBrlen\fR.
.sp
The 1284 device ID structure:
.sp
.in +2
.nf
struct ecpp_device_id {
  int  mode; /* mode to use for reading device id */
  int  len;  /* length of buffer */
  int  rlen;  /* actual length of device id string */
  char *addr; /* buffer address */
.fi
.in -2

.LP
Note -
.sp
.RS 2
Unlike \fBecpp\fR(4D), only the ECPP_CENTRONICS mode is currently supported in
\fBusbprn\fR.
.RE
.RE

.SH READ OPERATION
The \fBread\fR operation is not supported and returns \fBEIO\fR.
.SH ERRORS
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 19n
The device has been opened and another open is attempted. An attempt has been
made to unload the driver while one of the units is open.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 19n
An unsupported IOCTL has been received. A ECPPIOC_SETPARMS \fBioctl\fR(2) is
attempted with an out of range value in the \fBecpp_transfer_parms\fR
structure.
.RE

.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 19n
The driver has received an unrecoverable device error, or the device is not
responding, or the device has stalled when attempting an access. A
\fBwrite\fR(2) or \fBioctl\fR(2) did not complete due to a peripheral access. A
\fBread\fR(2) system call has been issued.
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 19n
The driver has received an \fBopen\fR(2) request for a unit for which the
attach failed.
.RE

.sp
.ne 2
.na
\fB\fBENODEV\fR\fR
.ad
.RS 19n
The driver has received an \fBopen\fR(2) request for a device that has been
disconnected.
.RE

.sp
.ne 2
.na
\fB\fBEPROTONOSUPPORT\fR\fR
.ad
.RS 19n
The driver has received a ECPPIOC_SETPARMS \fBioctl\fR(2) for a mode argument
other than ECPP_CENTRONICS in the \fBecpp_transfer_parms\fR structure.
.RE

.SH FILES
.ne 2
.na
\fB\fB/kernel/drv/usbprn\fR\fR
.ad
.RS 30n
32-bit x86 ELF kernel module
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/amd64/usbprn\fR\fR
.ad
.RS 30n
64-bit x86 ELF kernel module
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/sparcv9/usbprn\fR\fR
.ad
.RS 30n
64-bit SPARC ELF kernel module
.RE

.sp
.ne 2
.na
\fB/dev/usb/*/*/* \fR
.ad
.RS 30n
ugen(4D) nodes.
.RE

.sp
.ne 2
.na
\fB\fB/dev/printers/\fIn\fR\fR\fR
.ad
.RS 30n
Character special files
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Architecture	SPARC, x86, PCI-based systems
.TE

.SH SEE ALSO
.BR ioctl (2),
.BR open (2),
.BR read (2),
.BR write (2),
.BR ecpp (4D),
.BR ugen (4D),
.BR usba (4D),
.BR prnio (4I),
.BR attributes (7),
.BR cfgadm_usb (8),
.BR printmgr (8),
.BR attach (9E)
.sp
.LP
\fIWriting Device Drivers\fR
.sp
.LP
\fIUniversal Serial Bus Specification 1.0 and 1.1\fR
.sp
.LP
\fIUSB Device Class Definition for Printing Devices 1.0\fR
.sp
.LP
\fISystem Administration Guide: Basic Administration\fR
.SH DIAGNOSTICS
In addition to being logged, the following messages may appear on the system
console. All messages are formatted in the following manner:
.sp
.in +2
.nf
Warning: <device path> (usbprn<instance num>): Error Message...
.fi
.in -2
.sp

.sp
.ne 2
.na
\fBDevice was disconnected while open. Data may have been lost.\fR
.ad
.sp .6
.RS 4n
The device has been hot-removed or powered off while it was open and a possible
data transfer was in progress. The job may be aborted.
.RE

.sp
.ne 2
.na
\fBCannot access <device>. Please reconnect.\fR
.ad
.sp .6
.RS 4n
There was an error in accessing the printer during reconnect. Please reconnect
the device.
.RE

.sp
.ne 2
.na
\fBDevice is not identical to the previous one on this port. Please disconnect
and reconnect.\fR
.ad
.sp .6
.RS 4n
A USB printer was hot-removed while open. A new device was hot-inserted which
is not identical to the original USB printer. Please disconnect the USB device
and reconnect the printer to the same port.
.RE

.sp
.ne 2
.na
\fBPrinter has been reconnected but data may have been lost.\fR
.ad
.sp .6
.RS 4n
The printer that was hot-removed from its USB port has been re-inserted again
to the same port. It is available for access but the job that was running prior
to the hot-removal may be lost.
.RE

.SH NOTES
The USB printer will be power managed if the device is closed.
.sp
.LP
If a printer is hot-removed before a job completes, the job is terminated and
the driver will return EIO. All subsequent opens will return \fBENODEV\fR. If a
printer is hot-removed, an LP reconfiguration may not be needed if a printer is
re-inserted on the same port. If re-inserted on a different port, an LP
reconfiguration may be required.
.sp
.LP
The USB Parallel Printer Adapter is not hotpluggable. The printer should be
connected to USB Parallel Printer Adapter before plugging the USB cable into
host or hub port and should be removed only after disconnecting the USB cable
of USB Parallel Printer Adapter from the host or hub port.
